home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 4 / Apprentice-Release4.iso / Source Code / Libraries / KPlib 1.3.5 / kplib.docs < prev    next >
Text File  |  1995-12-17  |  12KB  |  274 lines
  1.    *************************************************************************
  2.    *************************************************************************
  3.    **                                                                     **
  4.    **                   ----====  KPlib v1.3.5 ====----                   **
  5.    **                                                                     **
  6.    **                         a C++ Class Library                         **
  7.    **                                                                     **
  8.    **                          by Keith Pomakis                           **
  9.    **                          pomakis@pobox.com                          **
  10.    **                                                                     **
  11.    **                            Summer, 1994                             **
  12.    **          Released to the public domain on October 10, 1994          **
  13.    **                                                                     **
  14.    *************************************************************************
  15.    *************************************************************************
  16.  
  17.                            ****  Documentation  ****
  18.  
  19.  
  20. ****************************************************************************
  21. PURPOSE AND HISTORY
  22. ****************************************************************************
  23.  
  24. I know what you're saying to yourself:  "What, another class library?".
  25. Yup, that's exactly what this is.  My thesis work requires me to do a lot
  26. of C++ programming.  The availability of a good class library is
  27. essential to my work.  However, I didn't want to use any compiler-specific
  28. class libraries because I wanted to insure that my code was portable.  I
  29. didn't want to use a third-party class library for two reasons.  First,  I
  30. couldn't find anything out there that satisfied me, and second, even if I
  31. did, I'd hate the prospect of having to drag around third-party software
  32. with me wherever I went.  I'd rather be my own technical support.  So I
  33. wrote this class library.  So far it has served me very well.  I don't know
  34. how I would survive without it.  It is my hope that, in distributing this
  35. library, others will be able to use what I've put together to increase
  36. their own programming productivity.
  37.  
  38. Unfortunately, I have had no time to develop a good user's manual for the
  39. library.  Furthermore, I haven't had the opportunity to test the library on
  40. a compiler other than g++ 2.6.x (although I've heard that it also compiles
  41. well under CodeWarrior for the Macintosh).  Since C++ is still in it's
  42. pre-standard days and every compiler tends to be different, it wouldn't
  43. surprise me if some C++ compilers fail to compile the library.
  44.  
  45. As far as the user's manual goes, I believe that the library is fairly
  46. intuitive and self-explanatory.  A programmer should be able to understand
  47. how to use the library merely by perusing the "*.h" files.
  48.  
  49. Perhaps a good user's manual will be a future project of mine.
  50.  
  51. Version 1.3.5: December 12, 1995:
  52.     - fixed bug in KPBag<T>::operator KPList<T>() const.
  53.     - thanks to Manuel Ornato (ornato@onera.fr) for pointing this out.
  54.  
  55. Version 1.3.4: November 6, 1995:
  56.     - fixed bug in KPStack<T>::clear().
  57.     - thanks to Gilbert Ramirez Jr. (gram@merece.uthscsa.edu) for pointing
  58.       this out.
  59.  
  60. Version 1.3.3: August 8, 1995:
  61.     - fixed bug in KPSet<T>::operator-().
  62.  
  63. Version 1.3.2: July 10, 1995:
  64.     - modified KPArray::operator=() to be more efficient when the source
  65.       and destination arrays are of the same size.
  66.     - added KPPriorityQueue<T>::contains() and
  67.       KPPriorityQueue<T>::occurrences_of().
  68.     - thanks to Timo Eloranta (sttiel@uta.fi) for suggesting these changes.
  69.  
  70. Version 1.3.1: April 25, 1995:
  71.     - made various minor changes to increase compiler compatibility and
  72.       improve efficiency.
  73.  
  74. Version 1.3.0: April 22, 1995:
  75.     - sealed a memory leak in KPIterator<T>::remove_current().
  76.     - changed the return type of KPIterator<T>::remove_current() to void.
  77.     - added KPSet<T>::operator<() so that sets of sets are possible.
  78.     - added KPBag<T> class.
  79.  
  80. Version 1.2.2: January 6, 1995:
  81.     - fixed bug in KPQueue<T>::clear() function.
  82.     - removed problematic operator<<(KPString&, const T&) function.
  83.     - added discussion of explicit template instantiation to documentation.
  84.  
  85. Version 1.2.1: November 7, 1994:
  86.     - fixed a couple of non-g++ incompatibilities, bringing the library
  87.       a little closer to be compilable on other compilers.
  88.  
  89. Version 1.2: October 21, 1994:
  90.     - modified inline max and min functions in KPbasic.h to make them more
  91.       general.
  92.     - made several KPSet functions "const" correct.
  93.  
  94. Version 1.1: October 12, 1994
  95.     - appended prefix "KP" to class and file names to avoid name clashes
  96.       with existing libraries.
  97.     - fleshed document out a little more.
  98.  
  99. Version 1.0: October 10, 1994
  100.     - first release into the public domain.
  101.     - not actually labelled with a version number.
  102.  
  103.  
  104. ****************************************************************************
  105. DISCLAIMER
  106. ****************************************************************************
  107.  
  108. I am releasing this library to the public domain.  Therefore, people can use
  109. it, copy it, distribute it, modify it, and do whatever they want with it.
  110.  
  111. Although this library has been well thought out, tested, and used in real
  112. applications, it is not guaranteed to be bug-free.  Therefore, I am not
  113. responsible for anything that happens, either directly or indirectly, due to
  114. the usage of this library.
  115.  
  116. If you modify or add to this library in any way, I'd appreciate it if you
  117. dropped me a line (or Internet packet, whatever) telling me what you did.
  118. I'm always interested in potential improvements to my work!
  119.  
  120. Also, if you find any bugs (gasp!) or have any questions or comments about
  121. the library, you can contact me as well.  My e-mail address is
  122. "pomakis@pobox.com".  I'd be interested in hearing what you think!
  123.  
  124. Oh, one other thing... I've put a lot of work into this library, so I'd
  125. appreciate it if you kept my name attached to it when distributing or
  126. modifying it.
  127.  
  128.  
  129. ****************************************************************************
  130. REQUIREMENTS AND COMPATIBILITY
  131. ****************************************************************************
  132.  
  133. This library has been successfully compiled with GNU g++ version 2.6.x (a
  134. Free Software Foundation project) and Metrowerks CodeWarrior for the
  135. Macintosh.  I cannot guarantee that it will compile on other C++
  136. compilers.  However, I tried to keep it as "standard" as possible, so I am
  137. hopeful.
  138.  
  139. The library uses templates quite heavily, but does not make use of exception
  140. handling.
  141.  
  142. In order for the template classes in this library to successfully link with
  143. your projects using g++ 2.6.x, the command-line option
  144. "-fno-implicit-templates" should be used, and all required template classes
  145. and functions should be explicitly instantiated.  Unfortunately, this may
  146. also require the instantiations of templates that are indirectly used, such
  147. as the base classes of the classes being used.  Fortunately, the list of
  148. undefined symbols at link time will provide you with the names of the
  149. templates that need instantiations.  Unfortunately, this list is mangled.
  150. Fortunately, there are demanglers out there.  Unfortunately, I'm not going
  151. to tell you where.  Fortunately, this entire problem should go away in
  152. g++ 2.7.x.
  153.  
  154.  
  155. ****************************************************************************
  156. CONTENTS
  157. ****************************************************************************
  158.  
  159. The library consists of the following classes:
  160.  
  161.     KPList<T>
  162.         A two-way list that assumes nothing about its elements except they
  163.         correctly implement a default constructor and operator=().
  164.  
  165.     KPComparableList<T>
  166.         A subclass of KPList<T> which also assumes its elements can be
  167.         compared with operator==(), thus providing more powerful methods.
  168.  
  169.     KPSortableList<T>
  170.         A subclass of KPComparableList<T> which also assumes its elements
  171.         can be compared with operator<(), thus providing more powerful
  172.         methods.
  173.  
  174.     KPReadOnlyIterator<T>
  175.         An iterator with pointer-like semantics which can iterate over any
  176.         of the above lists for reading purposes only.
  177.  
  178.     KPIterator<T>
  179.         An iterator with pointer-like semantics which can iterate over any
  180.         of the above lists for the purpose of reading, modifying, deleting,
  181.         or adding elements to or from arbitrary locations in the list.
  182.  
  183.     KPArray<T>
  184.         A dynamically-sizable array that assumes nothing about its
  185.         elements except they correctly implement a default constructor
  186.         and operator=().
  187.  
  188.     KPComparableArray<T>
  189.         A subclass of KPArray<T> which also assumes its elements can be
  190.         compared with operator==(), thus providing more powerful methods.
  191.  
  192.     KPSortableArray<T>
  193.         A subclass of KPComparableArray<T> which also assumes its elements
  194.         can be compared with operator<(), thus providing more powerful
  195.         methods.
  196.  
  197.     KPQueue<T>
  198.         A queue that assumes nothing about its elements except they
  199.         correctly implement a default constructor and operator=().
  200.  
  201.     KPPriorityQueue<T>
  202.         A priority queue that assumes its elements correctly implement
  203.         a default constructor, operator=(), operator==() and operator<().
  204.  
  205.     KPStack<T>
  206.         A stack that assumes nothing about its elements except they
  207.         correctly implement a default constructor and operator=().
  208.  
  209.     KPSet<T>
  210.         A set that assumes its elements correctly implement a default
  211.         constructor, operator=(), operator==() and operator<().  All
  212.         union, intersection and difference operations are of order O(n).
  213.  
  214.     KPBag<T>
  215.         A bag that assumes its elements correctly implement a default
  216.         constructor, operator=(), operator==() and operator<().
  217.  
  218.     KPString
  219.         A string class which implements basic string functions and more
  220.         (such as tokenizing methods which return List<String>).  This
  221.         class uses reference counting and copy-on-write semantics to
  222.         insure that it as efficient as possible.
  223.  
  224.  
  225. ****************************************************************************
  226. USAGE
  227. ****************************************************************************
  228.  
  229. The library consists of the following files:
  230.  
  231.         KPArray.h
  232.         KPBag.h
  233.         KPList.h
  234.         KPPriorityQueue.h
  235.         KPQueue.h
  236.         KPSet.h
  237.         KPStack.h
  238.         KPString.cxx
  239.         KPString.h
  240.         KPbasic.h
  241.  
  242. These files should be kept together in a single directory.  The name of each
  243. file directly represents what one would expect of its contents.  The file
  244. "KPbasic.h" contains a few basic functions and definitions that you might
  245. find convenient.
  246.  
  247. All of the classes in this library, except for KPString, are template
  248. classes.  Therefore, it easy to use these classes with your own classes as
  249. well as with all of the predefined data types.  The classes were not written
  250. to be easily derived from.
  251.  
  252. "KPString.cxx" is the only source file of the library.  In order to use this
  253. class it will have to be compiled with the rest of your code.  See the
  254. files in the accompanying "sample_progs" directory to see how this can be
  255. done conveniently.  Alternatively, "KPString.cxx" can be precompiled and
  256. converted to a library archive for standard linking.
  257.  
  258. See section "REQUIREMENTS AND COMPATIBILITY" for a discussion of explicit
  259. template instantiation and the g++ "-fno-implicit-templates" option.
  260.  
  261. Since I haven't actually written a user's guide for this library, the "*.h"
  262. files will have to suffice as documentation.
  263.  
  264. That's about it.  Enjoy!
  265.  
  266.  
  267. .--------------------+--------------------------------------------.
  268. | Keith Pomakis      | Don't take life too seriously.             |
  269. | pomakis@pobox.com  | After all, you'll never make it out alive. |
  270. +--------------------+--------------------------------------------+
  271. |     WWW home page: "http://csclub.uwaterloo.ca/u/kppomaki/"     |
  272. `-----------------------------------------------------------------'
  273.  
  274.